home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
PsL Monthly 1993 December
/
PSL Monthly Shareware CD-ROM (December 1993).iso
/
prgmming
/
dos
/
c
/
printq.exe
/
READ.ME
< prev
next >
Wrap
Text File
|
1993-05-23
|
11KB
|
237 lines
This file contains the following, released to the public domain:
PRINTQ.H: Header for PrintJob, PrintQueue classes, and the PrintJob-
derived classes PrintBuffer and PrintFile.
PRINTAPP.H: Header for using the print queue classes with Turbo Vision;
includes classes TPrintAppInit, TPrintApp and TPrintQueue.
PRINTQ.CPP: Source for classes declared in PRINTQ.H.
PRINTAPP.CPP: Source for classes declared in PRINTAPP.H
MAIN.CPP: Source for sample program.
These files show how to allow a Turbo Vision application to perform quasi-
background printing. Its not truly background printing, because small blocks
of text are printed during the application's idle() function. This means that
if there is a significant amount of time between calls to getEvent() that no
printing will be performed (IE if you're doing long calculations, or excessive
file i/o).
WARNING!!! The demo program (main.cpp) uses the class TPrintQueue, which
defines the printing operation to be performed by using DOS calls to print;
there is a bug in the TV library with TSystemError when a print error occurs
(run out of paper, printer is off-line, etc); if you use the TPrintQueue
presented here (or any time you use DOS to print in a TV app), you need to
fix the bug in TV. This entails:
1) In the header file SYSTEM.H, line 366: change:
static const char * const near errorString[14];
to have one more string:
static const char * const near errorString[15];
2) In the file TVTEXT2.CPP, line 138: add:
...
"Insert diskette in drive %c", // add the comma
"Printer not responding" // add this line
};
This is for versions of TV 1.03 and below; you'll have to check any future
versions to see if this has been corrected.
---------------------------------------------------------------------
The concept is rather simple. The class TPrintApp is derived from
TApplication, and virtually from TPrintAppInit. This means that you have to
specifically initialize TPrintAppInit in your app's ctor (just like with
TProgInit class). All that TPrintAppInit does (again, like TProgInit) is allow
a method for your class' ctor to initialize the static PrintQueue member. The
demo program shows how to do this.
Class TPrintApp overrides the following functions, for the following
reasons:
shutDown(): overridden to clean up printQueue.
idle(): this method gets called whenever TV is waiting for input (IE the
app is "idle"). Since the app's just sitting there doing nothing,
we call upon the printQueue to print() a small block of text. If you
use the TPrintQueue class included (or another that uses DOS to print)
and an error occurs, TV's TSystemError will overlay the statusline
with an error message, allowing the user to retry or cancel.
handleEvent(): overridden to allow an easy method to add print jobs to the
queue. If an evCommand event is received (command cmAddPrintJob),
this method casts the event.message.infoPtr to a PrintJob pointer,
ensures its not null, ensures it actually has something to print
(in case its ctor failed), ensures that there's a queue to put it
into, and inserts it into the queue. If all of this passes, then
the event is cleared; otherwise the PrintJob pointer is deleted
(important to note!) and the event is NOT cleared. This makes it so
that the calling function can check message()'s return value to ensure
that the job was added to the queue; if message() returns 0, then the
job has been deleted and NOT added to the queue.
valid(): overridden to see if printing is still going on when cmQuit is
issued. If there are still jobs in the queue when the app tries to
quit, valid() issues a messageBox warning the user that printing is
still going on and whether or not to cancel printing.
Class TPrintApp also adds the following:
initPrintQueue(): this *static* method is passed by default to
TPrintAppInit() as the default function which will create a PrintQueue
when called. If you want to use a different PrintQueue-derived class
(note that PrintQueue is a pure class and cannot be instantiated)
then just define a function which returns one of your objects and
pass it to TPrintAppInit() in your app's ctor initialization list.
Its best (encapsulation) to make this function a static method of your
app.
printQueue: this static variable is the print queue. Its assigned in
TPrintApp's ctor by a call to createPrintQueue() - which is the same
function you passed to TPrintAppInit().
Class TPrintQueue:
This class is derived from PrintQueue. All it does is to override the
pure virtual method printString() to use DOS to print.
Class PrintQueue:
This class is a simple collection of PrintJobs, defining the following
operations:
Ctor/dtor: the default ctor (ie PrintQueue()) just initializes the queue
as empty; the dtor (~PrintQueue()) calls killAll() to kill (delete)
all jobs in the queue.
insert(): returns True if the job is not null and is inserted successfully
into the queue; otherwise returns False.
kill(): kills (deletes) the job if its in the queue. Also: if the job is
the current job and its already started printing, calls the virtual
method printFormFeed() to eject the current page from the printer.
killAll(): calls kill() for each job in the queue, then frees all memory
being used by the queue.
currentJob(): return a pointer to the current job; if there isn't one
(queue is empty) returns null.
print(): does nothing if the queue is empty; otherwise it calls upon the
current job to set a char* to the text to print and to return the
length of that text (note that the amount of text printed per call
to print() is determined by the PrintJob, not by the queue). If the
char* was not set to null and the length was > 0, then calls the
virtual method printString() to print the text, and then tells the
job to skip() the number of bytes that were actually printed by
printString(). If the job is now complete() (all its text printed)
then the current job is deleted (with kill()), printFormFeed() is
called, and now the next job (if there is one) is ready to be
printed on the next call to print().
printString(): this is a pure virtual function - any class derived from
PrintQueue MUST override this function to perform the actual printing.
It should accept a const char* to the text to print, and an int to
the length of the text; it should return the number of bytes printed.
printFormFeed(): virtual; the default printFormFeed() just does:
return Boolean( printString("\f",1) == 1);
setJobsSize(): called upon to expand the internal buffer when a job is
added to the queue.
jobs: buffer which holds the PrintJob pointers. jobs[0] is the current
job.
count: number of items in the queue.
limit: number of items that can be stored in jobs.
Class PrintJob:
This class by default does nothing. To be useful, its virtual methods must
be overridden by a derived class.
Ctor/dtor: the ctor requires that you pass it the printSize - this is the
maximum number of bytes that will be returned by getText() (ie the
maximum bytes printed at a time). This number should not be too big
or it will slow down TV. My demo (run on a 386-33) uses 128 bytes,
and ran fine. For faster/slower machines, you may have to experiment
to find a good size. The dtor is virtual, and does nothing.
reset(): just repositions pos back to 0.
getText(): does nothing; in a useful derivative class, this method will
set the buf argument to point to the text to be printed (pos indicates
the current position) and returns the length of the bytes to be
printed. This returned value should be <= printSize.
skip(): increments pos by the passed argument (pos += n). If this sets
pos past the size, pos is set to size. Whenever the PrintQueue
successfully prints some chars, it will call this function to increment
the current print starting position.
complete(): Returns True if the job has been completed, F